home *** CD-ROM | disk | FTP | other *** search
/ The 640 MEG Shareware Studio 4 / The 640 Meg Shareware Studio CD-ROM Volume IV (Data Express)(1994).ISO / clang / cenvid.zip / CMMTUTOR.DOC < prev    next >
Text File  |  1993-08-10  |  47KB  |  1,095 lines
  1.                     CEnvi Shareware Manual, Chapter 2:
  2.                            Cmm Language Tutorial
  3.  
  4.  
  5.                       CEnvi unregistered version 1.0
  6.                               10 AUGUST 1993
  7.  
  8.                        CEnvi Shareware User's Manual
  9.  
  10.           Copyright 1993, Nombas, All Rights Reserved.
  11.           Published by Nombas, P.O. Box 875, Medford, MA 02155 USA
  12.           (617)391-6595, (617)391-5289
  13.  
  14.           Thank you for trying this shareware version of CEnvi from Nombas.
  15.  
  16. 2.  The Cmm Language: Tutorial for Non-C Programmers
  17.  
  18.           The information in this chapter is geared toward those who are
  19.           not familiar with the C programming language.  C programmers
  20.           should jump ahead to the next chapter: Cmm versus C.  This
  21.           section is an introduction to and description of the Cmm
  22.           programming language.
  23.  
  24.           If you can write a batch, script, or macro file, or if you can
  25.           remember what "y = x + 1" means from your algebra class, then
  26.           you're ready to take on Cmm.  Really.  Cmm contains only
  27.           variables, mathematics symbols (remember algebra), and these few
  28.           statements: IF, ELSE, DO, WHILE, FOR, SWITCH, CASE, BREAK,
  29.           DEFAULT, CONTINUE, GOTO, and RETURN.
  30.  
  31.           This section is an abbreviation of the Cmm Language Tutorial
  32.           chapter in the CEnvi registered manual.  The CEnvi registered
  33.           manual goes into much more depth, has many more examples, and
  34.           follows a step-by-step tutorial to create a simple text editor
  35.           with CEnvi.
  36.  
  37. 2.1.  Your first Cmm program
  38.  
  39.           Before going into a description of Cmm, let's first make sure
  40.           that CEnvi is working properly.  With a text editor (e.g., EDIT
  41.           for DOS, E for OS/2, or NOTEPAD for Windows) create the file
  42.           HELLO.CMM and enter this text:
  43.  
  44.               // Hello.cmm: My first Cmm program
  45.               Count = 1; /* Count is how many Cmm programs I've written */
  46.               printf("Hello world. This is my %dst Cmm program.\n",Count);
  47.               printf("Press any key to quit...");
  48.               getch();
  49.  
  50.           You have now written a Cmm program named "HELLO.CMM".  Don't be
  51.           concerned if you do not yet understand the HELLO.CMM program; it
  52.           should become clear as Cmm is defined.  Now execute this program
  53.           (for DOS or OS/2 you would enter "CENVI HELLO.CMM" and for
  54.           Windows you need may use the File Manager and double-click on the
  55.           file name).  You should get this output:
  56.  
  57.               Hello world. This is my 1st Cmm program.
  58.               Press any key to quit...
  59.  
  60.  
  61.           If this program will execute, then you are ready to go on to
  62.           learn about Cmm.  If it did not execute then consult the CEnvi
  63.           installation section in the first chapter of this shareware
  64.           manual.
  65.  
  66. 2.2.  Cmm comments
  67.  
  68.           Comments are used in Cmm code to explain what the code does, but
  69.           the comment itself does nothing.  Comments are very useful in
  70.           programming.  A comment takes nothing away from the execution of
  71.           a program, but adds immeasurably to the readability of the source
  72.           code.
  73.  
  74.           In Cmm, any text on a line following two slash characters (//) is
  75.           considered a comment and so is ignored by the Cmm interpreter.
  76.           Likewise, anything between a slash-asterisk (/*) and an
  77.           asterisk-slash (*/) is a comment (this type of comment may extend
  78.           over many lines).  In the HELLO.CMM program there is a "//"
  79.           comment on the first line and a "/* blah blah */" comment on the
  80.           second line.
  81.  
  82. 2.3.  Cmm primary data types
  83.  
  84.           There are three principal data types in Cmm:
  85.             *Byte: A character (e.g., 'D') or a whole number between 0 and
  86.               255, inclusive
  87.             *Integer: A whole number value; this is the most common numeric
  88.               data type (examples: 0, -1000, 567, 4335600)
  89.             *Float: floating point numbers; any number containing a decimal
  90.               point (examples: 0.567, 3.14159, -5.456e-12)
  91.  
  92.           Cmm determines the data type of a number by how it is used; for
  93.           example, in the HELLO.CMM program the "1" in the second line is
  94.           an integer because that is the default type for numbers without a
  95.           decimal point.
  96.  
  97. 2.4.  Cmm Variables
  98.  
  99.           A Cmm variable is a symbol that may be assigned data.  The
  100.           assignment of data is usually performed by the equal sign (=), as
  101.           in the line "Count = 1" in HELLO.CMM.  After variables have been
  102.           assigned, they can be treated as their data type.  So, after
  103.           these statements:
  104.               Count = 1               // assign count as the integer 1
  105.               Count = Count + 2       // same as: Count = 1 + 2
  106.           Count would now have the value 3.
  107.  
  108. 2.5.  Cmm Expressions, Statements, and Blocks
  109.  
  110.           A Cmm "expression" or "statement" is any sequence of code that
  111.           perform a computation or take an action (e.g., "Count=1",
  112.           "(2+4)*3").  Cmm code is executed one statement at a time in the
  113.           order it is read.  A Cmm program is a series of statements
  114.           executed sequentially, one at a time.  Each line of HELLO.CMM,
  115.           for example, follows the previous line as it is written and as it
  116.           is executed.
  117.  
  118.           A statement usually ends in a semicolon (;) (this is required in
  119.           C, and still a good idea in Cmm to improve readability).  Each
  120.           program statement is usually written on a separate line to make
  121.           the code easy to read.
  122.  
  123.           Expressions may be grouped to effect the sequence of processing;
  124.           expressions inside parentheses are processed first.  Notice that:
  125.               4 * 7 - 5 * 3       // 28 - 14 = 13
  126.           has the same meaning, do to algebraic operator precedence, as:
  127.               (4 * 7) - (5 * 3)   // 28 - 15 = 13
  128.           but has a different meaning than:
  129.               4 * (7 - 5) * 3     // 4 * 2 * 3 = 8 * 3 = 24
  130.           which is still different from:
  131.               4 * (7 - (5 * 3))   // 4 * (7 - 15) = 4 * -8 = -32
  132.  
  133.           A "block" is a group of statements enclosed in curly braces ({})
  134.           to show that they are all a group and so are treated as one
  135.           statement.  For example, HELLO.CMM may be rewritten as:
  136.               // Hello.cmm: My first Cmm program
  137.               Count = 1; /* Count is how many Cmm programs I've written */
  138.               printf("Hello world. This is my %dst Cmm program.\n",Count);
  139.               {
  140.                 // this block tells the user we're done, and quits
  141.                 printf("Press any key to quit...");
  142.                 getch();
  143.               }
  144.           The indentation of statements is not necessary, but is useful for
  145.           readability.
  146.  
  147. 2.6.  Cmm Mathematical Operators
  148.  
  149.           Cmm code usually contains some mathematical operations, such as
  150.           adding numbers together, multiplying, dividing, etc.  These are
  151.           written in a natural way, such as "2 + 3" when you want to add
  152.           two and three.  The next few subsections define the recognized
  153.           operators within the comments of sample code:
  154.  
  155. 2.6.1   Basic Arithmetic
  156.  
  157.               //  "="  assignment: sets a variable's value
  158.               i = 2;      // i is 2
  159.  
  160.               //  "+"  addition: adds two numbers
  161.               i = i + 3;  // i is now (2+3) or 5
  162.  
  163.               //  "-"  subtraction: subtracts a number
  164.               i = i - 3;  // i is now (5-3) or 2 again
  165.  
  166.               //  "*"  multiplication:
  167.               i = i * 5;  // i is now (2*5) or 10
  168.  
  169.               //  "/"  division:
  170.               i = i / 3;  // i is now (10/3) or 3 (no remainder)
  171.  
  172.               //  "%"  remainder: remainder after division
  173.               i = 10;
  174.               i = i % 3;  // i is now (10%3) or 1
  175.  
  176. 2.6.2   Assignment Arithmetic
  177.  
  178.           Each of the above operators can combined with the assignment
  179.           operator (=) as a shortcut.  This automatically assumes that the
  180.           assigned variable is the first variable in the arithmetic
  181.           operation.  Using assignment arithmetic operators, the above code
  182.           could be simplified as follows:
  183.  
  184.               //  "="  assignment: sets a variable's value
  185.               i = 2;      // i is 2
  186.  
  187.               //  "+="  assign addition: adds number
  188.               i += 3;     // i is now (2+3) or 5
  189.  
  190.               //  "-="  assign subtraction: subtracts a number
  191.               i -= 3;     // i is now (5-3) or 2 again
  192.  
  193.               //  "*="  assign multiplication:
  194.               i *= 5;     // i is now (2*5) or 10
  195.  
  196.               //  "/="  assign divide:
  197.               i /= 3;     // i is now (10/3) or 3 (no remainder)
  198.  
  199.               //  "%="  assign remainder: remainder after division
  200.               i = 10;
  201.               i %= i % 3; // i is now (10%3) or 1
  202.  
  203. 2.6.3   Auto-Increment (++) and Auto-Decrement (--)
  204.  
  205.           Other arithmetic shortcut are the auto-increment (++) and
  206.           auto-decrement (--) operators.  These operators add or subtract 1
  207.           (one) from the value to which they are applied.  ("i++" is a
  208.           shortcut for "i+=1", which is itself shortcut for "i=i+1").
  209.           These operators can be used before (prefix) or after (postfix)
  210.           their variables.  If used before, then the variable is altered
  211.           before it is used in the statement; if used after, then the
  212.           variable is altered after it is used in the statement.  This is
  213.           demonstrated by the following code sequence:
  214.  
  215.               i = 4;    // i is initialized to 4
  216.               j = ++i;  // j is 5, i is 5 (i was incremented before use)
  217.               j = i++;  // j is 5, i is 6 (i was incremented after use)
  218.               j = --i;  // j is 5, i is 5 (i was decremented before use)
  219.               j = i--;  // j is 5, i is 4 (i was decremented after use)
  220.  
  221. 2.7.  Cmm Arrays and Strings
  222.  
  223.           An "array" is a group of individual data elements.  Each
  224.           individual item in the array is then called an "array element".
  225.           An element of an array is itself a variable, much like any other
  226.           variable.  Any particular element of the array is selected by
  227.           specifying the element's offset in the array.  This offset is an
  228.           integer in square brackets ([]).  For example:
  229.  
  230.               prime[0] = 2;
  231.               prime[1] = 3;
  232.               prime[2] = 5;
  233.               month[0] = "January";
  234.               month[1] = "February";
  235.               month[2] = "March";
  236.  
  237.           An array in Cmm does not need to be pre-defined for size or data
  238.           type, as it does in other languages.  Any array extends from
  239.           minus infinity to plus infinity (within reasonable computer
  240.           memory limits).  The data type for the array is the type of the
  241.           data first assigned to it.
  242.  
  243.           If Cmm code begins with:
  244.               foo[5] = 7;
  245.               foo[2] = -100;
  246.               foo[-5] = 4;
  247.           then foo is an array of integers and the element at index 7 is a
  248.           5, at index 2 is -100, and at index -5 is 4.  "foo[5]" can be
  249.           used in the code anywhere that a variable could be used.
  250.  
  251. 2.7.1   Array Initialization
  252.  
  253.           Arrays can be initialized by initializing specific elements, as
  254.           in:
  255.               foo[5] = 7; foo[2] = -100; foo[-5] = 4;
  256.           or by enclosing all the initial statements in curly braces, which
  257.           will cause the array to start initializing at element 0, as in:
  258.               foo = { 0, 0, -100, 0, 0, 7 };
  259.  
  260. 2.7.2   Strings
  261.  
  262.           Strings are arrays of bytes that end in the null-byte (zero).
  263.           "String" is just a shorthand way to specify this array of bytes.
  264.           A string is most commonly specified simply by writing text within
  265.           two quote characters (e.g., "I am a string.")
  266.  
  267.           If this statement were present in the Cmm code:
  268.               animal = "dog";
  269.           it would be identical to this statement:
  270.               animal = { 'd', 'o', 'g', 0 };
  271.           and in both cases the value at animal[0] is 'd', at animal[2] is
  272.           'g', and at animal[3] is 0.
  273.  
  274. 2.7.3   Array Arithmetic
  275.  
  276.           When one array is assigned to the other, as in:
  277.               foo = "cat";
  278.               goo = foo;
  279.           then both variables define the same array and start at the same
  280.           offset 0.  In this case, if foo[2] is changed then you will find
  281.           that goo[2] has also been changed.
  282.  
  283.           Integer addition and subtraction can also be performed on arrays.
  284.           Array addition or subtraction sets where the array is based.  By
  285.           altering the previous code segment to:
  286.               foo = "cat";
  287.               goo = foo + 1;
  288.           goo and foo would now be arrays containing the same data, except
  289.           that now goo is based one element further, and foo[2] is now the
  290.           same data as goo[1].
  291.  
  292.           To demonstrate:
  293.               foo = "cat";  // foo[0] is 'c', foo[1] = 'a'
  294.               goo = foo + 1;// goo[0] is 'a', goo[-1] = 'c'
  295.               goo[0] = 'u'; // goo[0] is 'u', foo[1] = 'u', foo is "cut"
  296.               goo++;        // goo[0] is 't', goo[-2] = 'c'
  297.               goo[-2] = 'b' // goo[0] is 't', foo[0] = 'b', foo is "but"
  298.  
  299. 2.7.4   Multi-Dimensional Arrays: Arrays of Arrays
  300.  
  301.           An array element is a variable, and so if the type of that
  302.           element's variable is itself an array, then you have an array of
  303.           arrays.  A statement such as:
  304.               goo[4][2] = 5;
  305.           indicates that goo is an array of arrays, and that element 2 of
  306.           element 4 is the integer 5.
  307.  
  308.           Multi-dimensional arrays might be useful for programming a
  309.           tic-tac-toe game.  Each row and column of the 3x3 board could be
  310.           represented with a row, column element containing 'X', 'O' or ' '
  311.           (blank) depending on the character at that location.  For
  312.           example, a horizontal 'X' win in the middle row could be
  313.           initialized like this:
  314.               board[1][0] = 'X';
  315.               board[1][1] = 'X';
  316.               board[1][2] = 'X';
  317.  
  318.           Note that a string is an array, and so anytime you make an array
  319.           of strings you are defining an array of arrays.
  320.  
  321. 2.8.  Cmm Structures
  322.  
  323.           A "structure" is a collection of named variables that belong
  324.           together as a whole.  Each of the named variables in a structure
  325.           is called a member of that structure and can be any data type
  326.           (integer, float, array, another structure, array of structures,
  327.           etc.).  These structure members are associated with the structure
  328.           by using a period between the structure variable and the member
  329.           name.
  330.  
  331.           A simple and useful example of a structure is to specify a point
  332.           on the screen.  A point is made up of a row and column, and so
  333.           you may specify:
  334.               place.row = 12;   // set to row 12
  335.               place.col = 20;   // set at column 20
  336.               place.row--;      // move up one row to row 11
  337.  
  338.           Two structures can be compared for equality or inequality, and
  339.           they may be assigned, but no other arithmetic operations can be
  340.           performed on a structure.
  341.  
  342. 2.9.  printf() and getch()
  343.  
  344.           Although although the Cmm "function" has not yet been defined, it
  345.           is useful to use two functions already, printf() and getch(), for
  346.           learning more about Cmm programming.  Unfortunately, printf() is
  347.           about as complicated as a function can get.
  348.  
  349. 2.9.1   printf() Syntax
  350.  
  351.           printf() prints to the screen, providing useful feedback on your
  352.           programming.  The basic syntax of printf() is this:
  353.  
  354.               printf(FormatString,data1,data2,data3,...);
  355.  
  356.           FormatString is the string that will be printed to the screen.
  357.           When FormatString contains a percent character (%) followed by
  358.           another character, then instead of printing those characters
  359.           printf() will print the next data item (data1, data2, data3,
  360.           etc...).  The way the data will be presented is determined by the
  361.           characters immediately following the percent sign (%).  There are
  362.           many such data formats, as described fully in the Registered
  363.           User's Manual (or any C programming manual), but here's few to
  364.           start with:
  365.             *%%  print a percentage sign
  366.             *%d  print a decimal integer
  367.             *%X  print a hexidecimal integer
  368.             *%c  print a character
  369.             *%f  print a floating-point value
  370.             *%E  print a floating-point value in scientific format
  371.             *%s  print a string
  372.  
  373.           There are also special characters that cause unique screen
  374.           behavior when they are printed, some of which are:
  375.             *\n  goto beginning of next line
  376.             *\t  tab
  377.             *\a  alarm: audible beep
  378.             *\r  carriage-return without a line feed
  379.             *\"  print the quote character
  380.             *\\  print a backslash
  381.  
  382.           Here are some example printf() statements:
  383.               printf("Hello world. This is my %dst Cmm program.\n",Count);
  384.               printf("%c %d %dlips",'I',8,2);
  385.               printf("%d decimal is the same as %X in hexidecimal",n,n);
  386.               printf("My name is: %s\n","Mary");
  387.  
  388. 2.9.2   getch() Syntax
  389.  
  390.           getch() (GET CHaracter) waits for any key to be pressed.  The
  391.           program stops executing at the getch() statement until a key is
  392.           pressed.  getch() is especially useful in Windows because once a
  393.           program is completed its windows will go away.  So getch() might
  394.           be placed at the end of the program to keep the screen visible
  395.           until a key is pressed.
  396.  
  397. 2.9.3   Using printf() and getch() to Learn Cmm
  398.  
  399.           You can now experiment with what you are learning by using the
  400.           printf() and getch() statements.
  401.  
  402.           If, during program execution, you want to know that you're about
  403.           to execute an exciting piece of code, then before those
  404.           interesting lines of code you may want to write:
  405.  
  406.               printf("Here comes the good stuff.  Press any key...");
  407.               getch();
  408.  
  409.           You can display values at any point in your program with a
  410.           printf() statement.  This short TEST.CMM program tests how "*="
  411.           works:
  412.  
  413.               // TEST.CMM - test the *= operator
  414.               var1 = 4;
  415.               var2 = 5;
  416.               printf("the numbers are %d and %d\n",var1,var2);
  417.               var1 *= 7;
  418.               var2 *= 7;
  419.               printf("after *= 7 the values are %d and %d\n",var1,var2);
  420.               getch();
  421.  
  422. 2.10. Bit Operators
  423.  
  424.           Cmm contains many operators for operating on the binary bits in a
  425.           byte or an integer.  If you're not familiar with hexidecimal
  426.           numbering (digits '0' to 'F'), you may want to refer to the CEnvi
  427.           Registered User's Manual.
  428.  
  429.               i = 0x146;
  430.  
  431.               //  "<<"  shift left: shift all bits left by value
  432.               //  "<<=" assignment shift left
  433.               i <<= 2;    // shift i (0x146) left 2, so i = 0x518
  434.  
  435.               //  ">>"  shift right: shift all bits right by value
  436.               //  ">>=" assignment shift right
  437.               i >>= 3;    // shift i (0x518) right 3, so i = 0xA3
  438.  
  439.               //  "&"   bitwise AND
  440.               //  "&="  assignment bitwise and
  441.               i &= 0x35;  // and i (0xA3) with 0x35 so i = 0x21
  442.  
  443.               //  "|"   bitwise OR
  444.               //  "|="  assignment bitwise OR
  445.               i |= 0xC5;    // OR i (0x21) with 0xC4 so i = 0xE5
  446.  
  447.               //  "^"   bitwise XOR: exlusive OR
  448.               //  "^="  assignment bitwise XOR
  449.               i ^= 0xF329 // XOR i (0xE5) with so i = 0xF3CC
  450.  
  451.               //  "~"   Bitwise complement: (turn 0 bits to 1, and 1 to 0)
  452.               i = ~i;     // complement i (0xF3CC) so i = 0xFFFF0C33 (OS/2)
  453.  
  454. 2.11. Logical Operators and Conditional Expressions
  455.  
  456.           A conditional expression is evaluated to be TRUE or FALSE, where
  457.           FALSE means zero, and TRUE means anything that is not FALSE
  458.           (i.e., not zero).  A variable or any other expression by itself
  459.           can be TRUE or FALSE (i.e., non-zero or zero).  With logic
  460.           operators, these expressions can be combined to make encompassing
  461.           TRUE/FALSE decisions.  The logic operators are:
  462.  
  463.             *"!"   NOT: opposite of decision
  464.               !TRUE               // FALSE
  465.               !FALSE              // TRUE
  466.               !('D')              // FALSE
  467.               !(5-5)              // TRUE
  468.  
  469.             *"&&"  AND: TRUE if and only if both expressions are true
  470.               TRUE && FALSE       // FALSE
  471.               TRUE && TRUE        // TRUE
  472.               0 && (foo+2)        // FALSE: (foo+2) is not evaluated
  473.               !(5-5) && 4         // TRUE
  474.  
  475.             *"||"  OR: TRUE if either expression is TRUE
  476.               TRUE || FALSE       // TRUE: doesn't even check FALSE
  477.               TRUE || (4+2)       // TRUE: (4+2) is not evaluated
  478.               FALSE || (4+2)      // TRUE: (4+2) is evaluated
  479.               FALSE || FALSE      // FALSE
  480.               0 || 0.345          // TRUE
  481.               !(5-3) || 4         // TRUE
  482.  
  483.             *"=="  EQUALITY: TRUE if both values equal, else FALSE
  484.               5 == 5              // TRUE
  485.               5 == 6              // FALSE
  486.  
  487.             *"!="  INEQUALITY: TRUE if both values not equal, else FALSE
  488.               5 != 5              // FALSE
  489.               5 != 6              // TRUE
  490.  
  491.             *"<"   LESS THAN
  492.               5 < 5               // FALSE
  493.               5 < 6               // TRUE
  494.  
  495.             *"<"   GREATER THAN
  496.               5 > 5               // FALSE
  497.               5 > 6               // FALSE
  498.               5 > -1              // TRUE
  499.  
  500.             *"<="  LESS THAN OR EQUAL TO
  501.               5 <= 5              // TRUE
  502.               5 <= 6              // TRUE
  503.               5 <= -1             // FALSE
  504.  
  505.             *">="  GREATER THAN OR EQUAL TO
  506.               5 >= 5              // TRUE
  507.               5 >= 6              // FALSE
  508.               5 >= -1             // TRUE
  509.  
  510. 2.12. Flow Decisions: Loops, Conditions, and Switches
  511.  
  512.           This section describes how Cmm statements can control the flow of
  513.           your program.  You'll notice code sections are often indented,
  514.           when blocks belong together; this makes the code much easier to
  515.           read.
  516.  
  517. 2.12.1  IF - Execute statement (or block) if conditional expression is TRUE
  518.  
  519.               if ( goo < 10 ) {
  520.                 printf("goo is smaller than 10\n");
  521.               }
  522.  
  523. 2.12.2  ELSE - Execute statement (or block) if IF block was not executed
  524.               if ( goo < 10 ) {
  525.                 printf("goo is smaller than 10\n");
  526.               } else {
  527.                 printf("goo is not smaller than 10\n");
  528.               }
  529.  
  530.           ELSE can also be combined with IF to find one in a series of
  531.           values:
  532.  
  533.               if ( goo < 10 ) {
  534.                 printf("goo is less than 10\n");
  535.                 if ( goo < 0 ) {
  536.                   printf("goo is negative; of course it's less than 10\n");
  537.                 }
  538.               } else if ( goo > 10 ) {
  539.                 printf("goo is greater than 10\n");
  540.               } else {
  541.                 printf("goo is 10\n");
  542.               }
  543.  
  544. 2.12.3  WHILE - Execute block while conditional expression is TRUE
  545.  
  546.               str = "WHO ARE YOU?";
  547.               while ( str[0] != 'A' ) {
  548.                 printf("%s\n",str);
  549.                 str++;
  550.               }
  551.               printf("%s\n",str);
  552.  
  553.           The output of the above code would be:
  554.               WHO ARE YOU?
  555.               HO ARE YOU?
  556.               O ARE YOU?
  557.                ARE YOU?
  558.               ARE YOU?
  559.  
  560. 2.12.4  DO ... WHILE - Execute block, and then test for conditional
  561.  
  562.           This is different from the WHILE statement in that the block is
  563.           executed at least once, before the condition is tested.
  564.  
  565.               do {
  566.                 value++;
  567.                 printf("value = %d\n",value);
  568.               } while( value < 100 );
  569.  
  570.           The code used to demonstrate the WHILE statement might be better
  571.           written this way to avoid the extra printf():
  572.  
  573.               str = "WHO ARE YOU?";
  574.               do {
  575.                 printf("%s\n",str);
  576.               } while ( str++[0] != 'A' );
  577.  
  578. 2.12.5  FOR - initialize, test conditional, then loop
  579.  
  580.           "for" is a combination of statements of this format:
  581.               for ( initialization; conditional; loop_expression )
  582.                 statement
  583.           The initialization is performed first.  Then the conditional is
  584.           tested.  If the conditional is TRUE (or if there is no
  585.           conditional expression) then statement is executed, and then the
  586.           loop_expression is executed, and so on back to testing the
  587.           conditional.  If the conditional is FALSE then the program
  588.           continues beyond statement.  The "for" statement is a shortcut
  589.           for this form of WHILE:
  590.               initialization;
  591.               while ( conditional ) {
  592.                 statement;
  593.                 loop_expression;
  594.               }
  595.  
  596.           The above code demonstrating the WHILE statement would be
  597.           rewritten this way if you preferred to use the FOR statement:
  598.  
  599.               for ( str = "WHO ARE YOU?"; str[0] != 'A'; str++ )
  600.                 printf("%s\n",str);
  601.               printf("%s\n",str);
  602.  
  603.  
  604. 2.12.6  BREAK and CONTINUE
  605.  
  606.           "break" terminates the nearest loop or case statement.
  607.  
  608.           "continue" jumps to the test condition in the nearest DO or WHILE
  609.           loop, and jumps to the loop_expression in the nearest FOR loop.
  610.  
  611. 2.12.7  SWITCH, CASE, and DEFAULT
  612.  
  613.           The SWITCH statement follows this format:
  614.  
  615.               switch( switch_expression ) {
  616.                 case exp1:  statement1
  617.                 case exp2:  statement2
  618.                 case exp3:  statement3
  619.                 case exp4:  statement4
  620.                 case exp5:  statement5
  621.                 .
  622.                 .
  623.                 .
  624.                 default: default_statement
  625.               }
  626.  
  627.           switch_expression is evaluated, and then it is compared to all of
  628.           the case expressions (expr1, expr2, expr3, etc...) until a match
  629.           is found (i.e., switch_expression == expr? ).  The statements
  630.           following that match are then executed until the end of the
  631.           switch block is reached or until a BREAK statement exits the
  632.           switch block.  If no match is found, the DEFAULT: statement is
  633.           executed if there is one.
  634.  
  635.           For example, this code handles the variable "key", which is
  636.           assumed to be the value of a key that was just pressed on the
  637.           keyboard:
  638.  
  639.               switch ( key ) {
  640.                 case '0':
  641.                 case '1':
  642.                 case '2':
  643.                 case '3':
  644.                 case '4':
  645.                 case '5':
  646.                 case '6':
  647.                 case '7':
  648.                 case '8':
  649.                 case '9:
  650.                   printf("A digit was pressed\n");
  651.                   break;
  652.                 case '\r';
  653.                   printf("You pressed RETURN\n");
  654.                 default:
  655.                   printf("I am not prepared for the key you pressed\n");
  656.                   break;
  657.               }
  658.  
  659. 2.12.8  GOTO and Labels
  660.  
  661.           You may jump to any location within a function block (see
  662.           functions) by using the GOTO statement.  The syntax is:
  663.               goto LABEL;
  664.           where LABEL is an identifier followed by a colon (:).
  665.  
  666.               if ( a < 0 ) {
  667.                 BadGoingsOn:      // this is a label
  668.                 printf("\aThe value for a is very bad.\n");
  669.                 abort();          // see function library for abort()
  670.               } else if ( 1000 < a )
  671.                 goto BadGoingsOn;
  672.  
  673.           GOTOs should be used sparingly, for they often make it difficult
  674.           to track program flow.
  675.  
  676. 2.13. Conditional Operator ?:
  677.  
  678.           The conditional operator is a strange-looking statement that is
  679.           simply a useful shortcut.  The syntax is this:
  680.  
  681.               test_expression ? expression_if_true : expression_if_false
  682.  
  683.           First, test_expression is evaluated.  If test_expression is
  684.           non-zero (TRUE) then expression_if_true is evaluated and the
  685.           value of the entire expression replaced by the value of
  686.           expression_if_true.  If test_expression is FALSE, then
  687.           expression_if_false is evaluated and the value of the entire
  688.           expression is that of expression_if_false.
  689.  
  690.           For example:
  691.               foo = ( 5 < 6 ) ? 100 : 200;  // foo is set to 100
  692.               printf("User's name is %s\n",NULL==name ? "unknown" : name);
  693.  
  694. 2.14. Functions
  695.  
  696.           Functions in Cmm can perform any action of any complexity, and
  697.           yet they are used in statements as easily as variables.  It is
  698.           because of the flexibility and simplicity of functions that Cmm
  699.           needs so few statements.  Any action can take place in a
  700.           function, and yet the function is treated by the calling code
  701.           simply as the data type that the function returns.
  702.  
  703. 2.14.1  Function definition
  704.  
  705.           A function takes a form such as this:
  706.  
  707.               FunctionName(Parameter1,Parameter2,Parameter3)
  708.               {
  709.                 statements...
  710.                 return result;
  711.               }
  712.  
  713.           where the function name is followed by a list of input parameters
  714.           in parentheses (there can be any number of input parameters and
  715.           they can be named with any variable names).
  716.  
  717.           A call is made to a function in this format:
  718.  
  719.               FunctionName(Value1,Value2,Value3)
  720.  
  721.           So any call to FunctionName will be result in the execution of
  722.           FunctionName() with the parameters passed, and then be equivalent
  723.           to whatever value FunctionName() returns.
  724.  
  725. 2.14.2  Function RETURN Statement
  726.  
  727.           The return statement causes a function to return to the code that
  728.           initially called the function.  The calling code will receive the
  729.           value that the function returned.  Here are function examples:
  730.  
  731.               foo(a,b)    // return a times b
  732.               {
  733.                 return( a * b );
  734.               }
  735.  
  736.               foo(a,b)    // return a times b
  737.               {
  738.                 return a * b;
  739.               }
  740.  
  741.               foo(a,b)    // return the minimum value of a and b
  742.               {
  743.                 if ( a < b )
  744.                   result = a;
  745.                 else
  746.                   result = b;
  747.                 return(result);
  748.               }
  749.  
  750.               foo(a,b)    // return a structure with members .min and .max
  751.               {           // for the smaller and larger of a and b
  752.                 if ( a < b ) {
  753.                   bounds.min = a;
  754.                   bounds.max = b; 
  755.                 } else {
  756.                   bounds.min = b;
  757.                   bounds.max = a;
  758.                 }
  759.                 return( bounds );
  760.               }
  761.  
  762.           If no value is returned, or if the end of the function block is
  763.           reached without a return statement, then no value is returned and
  764.           the function is a "void" type.  void functions return no value to
  765.           the calling code.  These examples demonstrate some void-returning
  766.           functions:
  767.  
  768.               foo(a,b)    // set a = b squared. No return value.
  769.               {
  770.                 a = b * b;
  771.                 return;
  772.               }
  773.  
  774.               foo(a,b)    // set a = b squared. No return value.
  775.               {
  776.                 a = b * b;
  777.               }
  778.  
  779. 2.14.3  Function Example
  780.  
  781.           The use of functions should gain clarity with this example.  This
  782.           code demonstrates a function that multiplies two integers
  783.           (although multiplying integers could more easily be performed
  784.           with the multiply (*) operator):
  785.  
  786.               num1 = 4;
  787.               num2 = 6;
  788.  
  789.               // use the standard method of multiplying numbers
  790.               printf("%d times %d is %d\n",num1,num2,num1*num2);
  791.  
  792.               // now call our function to do the same thing
  793.               printf("%d times %d is %d\n",num1,num2,Multiply(num1,num2));
  794.  
  795.                 // declare a function that multiplies two integers.  Notice
  796.                 // that the integers are defined as i and j, so that's how
  797.                 // they'll be called in this function, no matter what they
  798.                 // were named in the calling code.  This function will
  799.                 // return i added to itself j times.
  800.               Multiply(i,j)
  801.               {
  802.                 total = 0;
  803.                 for ( count = 0; count < j; count++ )
  804.                   total += i;
  805.                 return(total);  // caller will receive this value
  806.               }
  807.  
  808.           When executed, the above code will print:
  809.               4 times 6 is 24
  810.               4 times 6 is 24
  811.  
  812.           This example demonstrated several features of Cmm functions.
  813.           Notice that in calling printf() the parameter "num1*num2" is not
  814.           passed to printf, but the result of "num1*num2" is passed to
  815.           printf.  Likewise, "Multiply(num1,num2)" is not a parameter to
  816.           printf(); instead, printf receives the return value of Multiply()
  817.           as its parameter.
  818.  
  819. 2.14.4  Function Recursion
  820.  
  821.           When a function calls itself, or calls some other function that
  822.           calls itself, then it is known as a recursive function.
  823.           Recursion is permitted in Cmm, as it is in C.  Each call into a
  824.           function is independent of any other call to that function (see
  825.           section on variable scope).
  826.  
  827.           The following function, factor(), factors a number.  Factoring is
  828.           a natural candidate for recursion because it is a repetitive
  829.           process where the result of one factor is then itself factored
  830.           according to the same rules.
  831.  
  832.               factor(i)   // recursive function to print all factors of i,
  833.               {           // and return the number of factors in i
  834.                  if ( 2 <= i ) {
  835.                     for ( test = 2; test <= i; test++ ) {
  836.                        if ( 0 == (i % test) ) {
  837.                           // found a factor, so print this factor then call
  838.                           // factor() recursively to find the next factor
  839.                           printf(" %d",test);
  840.                           return( 1 + factor(i/test) );
  841.                        }
  842.                     }
  843.                  }
  844.                  // if this point was reached, then factor not found
  845.                  return( 0 );
  846.               }
  847.  
  848. 2.15. Variable Scope
  849.  
  850.           A variable in Cmm is either global or local.  A global variable
  851.           is one that is referenced outside of any function, making it
  852.           visible and accessible to all functions.  A local variable is one
  853.           that is only referenced inside of a function, and so it only has
  854.           meaning and value within the function that declares it.  Note
  855.           that two local variables in different functions are not the same
  856.           variable.  Also, each instance of a recursive function has its
  857.           own set of local variables.  In other words, a variable that is
  858.           not referenced outside of a function only has meaning (and that
  859.           meaning is unique) while the code for that function is executing.
  860.  
  861.           In the following sample code, "number" is the only global
  862.           variable, the two "result" variables in Quadruple() and Double()
  863.           are completely independent, and the "result" variable in one call
  864.           Double() is unique to each call to Double():
  865.  
  866.               number = Quadruple(3);
  867.  
  868.               Quadruple(i)
  869.               {
  870.                 result = Double(Double(i));
  871.                 return(result);
  872.               }
  873.  
  874.               Double(j)
  875.               {
  876.                 result = j + j;
  877.                 return(result);
  878.               }
  879.  
  880.           Note that variables that are all in uppercase letter are
  881.           considered global and refer to environment variables.  See the
  882.           chapter on CEnvi specifics for more on environment variables.
  883.  
  884. 2.16. #define
  885.  
  886.           "#define" is used to replace a token (a variable or a function
  887.           name) with other characters.  The structure is:
  888.               #define token replacement
  889.           This results in all subsequent occurrences of "token" to be
  890.           replaced with "replacement".  For example:
  891.               #define HI  "Hello world!"
  892.               printf(HI);
  893.           would result in the following output:
  894.               Hello world!
  895.           because HI was replaced with "Hello world!"
  896.  
  897.           A common use of #define is to define constant numeric or string
  898.           values that might possibly change, so that in the future only the
  899.           #define at the top of the file needs to be altered.  For
  900.           instance, if you write screen routines for a 25-line monitor, and
  901.           then later decide to make it a 50-line monitor, you're better off
  902.           altering
  903.               #define ROW_COUNT   25
  904.           to
  905.               #define ROW_COUNT   50
  906.           and using ROW_COUNT in your code (or ROW_COUNT-1, ROW_COUNT+2,
  907.           ROW_COUNT/2, etc...) than if you had to search for every instance
  908.           of the numbers 25, 24, 26, etc...
  909.  
  910.           CEnvi has a large default list of tokens that have already been
  911.           #define'd, such as TRUE, FALSE, and NULL.  More of these are
  912.           listed in the chapter on the Internal Function Library.
  913.  
  914. 2.17. #include
  915.  
  916.           Cmm code is executed from one stream of source code.  Sometimes
  917.           it is useful to break the program into different files or to
  918.           access commonly used code without recreating that code again and
  919.           again in every new program written.  This is what "#include" is
  920.           for: it allows code from another file to be included in a
  921.           program.
  922.  
  923.           The #include syntax is:
  924.  
  925.               #include <Name[,Ext[,Prefix[,BeginCode[,EndCode]]]]>
  926.               where:
  927.               Name - Name of the file to include
  928.               Ext - Extension name to add to Name if not already there
  929.               Prefix - Will only include code from Name on lines that begin
  930.                        with this string
  931.               BeginCode - Will start including code from Name following
  932.                           this line of text
  933.               EndCode - Will stop including code when this line is read
  934.  
  935.           The quote characters (' or ") may be used in place of < and >.
  936.           The only field that is required by Cmm is Name (this is the field
  937.           used in C's #include), which is the name of the file to include.
  938.           All other fields are optional, and can be left blank if unused.
  939.  
  940.           To include all of C:\CMM\LIB.cmm
  941.               #include <c:\CMM\LIB.cmm>
  942.           To include from dog.bat between the lines GOTO END and :END
  943.               #include 'dog,bat,,GOTO END,:END'
  944.           To include lots of little files into one big one program
  945.               #include <screen.cmm>
  946.               #include <keyboard.cmm>
  947.               #include <init.cmm>
  948.               #include <comm.cmm>
  949.  
  950. 2.18. Initialization
  951.  
  952.           All code that is outside of any function is part of the global
  953.           initialization function.  This code is executed first, before
  954.           calling any function (unless a function is called from this
  955.           initialization code).
  956.  
  957.           Any variables referenced in the initialization section are
  958.           global.
  959.  
  960. 2.19. main(ArgCount,ArgStrings)
  961.  
  962.           After the initialization has been performed, the main() function
  963.           is called and is given the argument input to the Cmm program.
  964.           The first parameter to main (ArgCount) is the number of arguments
  965.           provided to the program.  ArgStrings is an array of those input
  966.           arguments, which are always strings.  The first argument is
  967.           always the name of the source code, or of CEnvi.exe if there is
  968.           no source file.
  969.  
  970.           The value returned from main() should be an integer, and is the
  971.           exit code (ERRORLEVEL for DOS) returned to the operating system
  972.           from your program (see also exit() in the internal library).
  973.  
  974.           This code file TEST.CMM:
  975.               printf("I am initializing\n");
  976.               main(argc,argv)
  977.               {
  978.                 printf("This program is called %s.\n",argv[0]);
  979.                 printf("There are %d input arguments, as follows:\n",argc);
  980.                 for ( i = 0; i < argc; i++ )
  981.                   printf("\t%s\n",argv[i]);
  982.                 return(0);
  983.               }
  984.               printf("still initializing\n");
  985.           When executed in this way:
  986.               cenvi test.cmm I am 4 "years old" today
  987.           would result in this output:
  988.               I am initializing
  989.               still initializing
  990.               This program is called test.CMM.
  991.               There are 6 input arguments, as follows:
  992.                       test.CMM
  993.                       I
  994.                       am
  995.                       4
  996.                       years old
  997.                       today
  998.           and would return 0 to the operating system.
  999.  
  1000. -------------------------------- FILE LIST --------------------------------
  1001. The CEnvi Unregistered Shareware package includes the files in the
  1002. following list.  You are not permitted to upload or otherwise transfer
  1003. copies of any registered version of CEnvi that does not include all of the
  1004. files in this list.
  1005.  
  1006. *CENVI.EXE: CEnvi shareware executable for DOS, OS/2, or Windows.
  1007. *CENVI.DOC: CEnvi Shareware Manual, Chapter 1: CEnvi Unregistered Shareware
  1008. *CMMTUTOR.DOC: CEnvi Shareware Manual, Chapter 2: Cmm Language Tutorial
  1009. *CMM_VS_C.DOC: CEnvi Shareware Manual, Chapter 3: Cmm versus C, for C
  1010.   Programmers
  1011. *CENVILIB.DOC: CEnvi Shareware Manual, Chapter 4: Function Library
  1012. *FILELIST.DOC: This file.
  1013. *LICENSE.DOC: CEnvi Unregistered Shareware License Agreement
  1014. *REGISTER.DOC: CEnvi registration form
  1015. *INSTALL.CMM: Cmm source file for installing this shareware version
  1016. * *.CMM, *.CMD, *.BAT, *.LIB: Many many sample programs using CEnvi.  See
  1017.   CENVI.DOC for a complete list.
  1018.  
  1019. ----------------------------- REGISTRATION -------------------------------
  1020. This is a shareware release.  Please register.  As a registered CEnvi user
  1021. you will receive:
  1022. *The latest version of CEnvi for all supported platforms (currently DOS,
  1023.   OS/2, and Windows).
  1024. *The CEnvi user's manual (almost 100 pages, including a description of the
  1025.   Cmm programming language, a tutorial for those who have never programmed,
  1026.   and descriptions and examples of the nearly 150 functions included in the
  1027.   CEnvi library).
  1028. *Free incremental electronic downloads for new versions of CEnvi for all
  1029.   supported operating systems.
  1030. *Unlimited support from Nombas and CEnvi/Cmm users through CompuServe
  1031.   (72212,1622), internet (bsn@world.std.com), the cenvi-cmm e-mail mailing
  1032.   list (cenvi-cmm@world.std.com), and the Nombas BBS (617-391-6595).
  1033. *Access to the growing list of CEnvi utilities and libraries (some of which
  1034.   are included in this unregistered shareware package, and others are
  1035.   contributed by Nombas and CEnvi/Cmm users to the electronic locations
  1036.   described above).
  1037.  
  1038. ------------------------- CENVI REGISTRATION FORM -------------------------
  1039. Thank you for registering your shareware copy of CEnvi version 1.0.  Please
  1040. fill out and mail in this form, along with payment.
  1041.  
  1042. Where did you get CEnvi? ______________________________________________
  1043.  
  1044. Name: _________________________________________________________________
  1045.  
  1046. Company: ______________________________ Position: _____________________
  1047.  
  1048. Address: ______________________________________________________________
  1049.  
  1050. _______________________________________________________________________
  1051.  
  1052. ______________________________________________________________________
  1053.  
  1054. Country: _________________________   (add ZIPcode if applicable)
  1055.  
  1056. Phone: ___________________________  EMail: ______________________________
  1057.  
  1058.           Diskette size: [  ] 3.5"   [  ] 5.25"
  1059.  
  1060. CEnvi Registered License ............ Quantity _____ x $38.00 = $ _________
  1061. Additional CEnvi Registered licenses for your
  1062. organization (does not include additional manuals
  1063. or diskettes).  You must already be a registered
  1064. user to purchase additional licenses.
  1065.                     Additonal License Quantity _____ x $15.00 = $ _________
  1066. Additional CEnvi Manuals.  You must already be a 
  1067. registered user to purchase additional manuals.
  1068.                    Additional Manuals Quantity _____ x $10.00 = $ _________
  1069. Friend-of-Cmm Discount: enter $-5.00, and BBS
  1070. location, if you have uploaded CEnvi Unregistered
  1071. Shareware to a BBS where it wasn't already available.
  1072.     BBS Location ____________________________________________   $-_________
  1073. Shipping outside USA, Canada, or Mexico  $4.00 ................ $ _________
  1074.                                                        Subtotal $ _________
  1075. Massachusetts residents please add 5% sales tax ............... $ _________
  1076.  
  1077.                                                           Total $ _________
  1078.  
  1079. Include a check or money order for this total, in U.S. funds and drawn on a
  1080. U.S. bank, payable to Nombas.  Mail with this form to:
  1081.                Nombas
  1082.                P.O. Box 875
  1083.                Medford, MA  02155   USA
  1084.  
  1085. Nombas may also be contacted at:
  1086.      BBS: (617)391-6595
  1087.      Phone: (617)391-6595, (617)391-5289
  1088.      Internet: bsn@world.std.com
  1089.      CompuServe: 72212,1622
  1090.  
  1091.  
  1092. Nombas welcomes all comments, good or bad, regarding CEnvi and Cmm.  Please
  1093. use the back of this form to give us all your suggestions about CEnvi and
  1094. Cmm.  This is version 1.0; Where should we go from here?
  1095.